乐摇摇

针对厂商设备主板与乐摇摇串口联网模组对接，平台提供标准串口数据通讯协议、自动生成参数界面、串口调试工具，简化开发过程，使设备快速联网获得增值功能。本文档基于乐摇摇串口联网模组与设备主板的标准对接流程编写。

协议文档

下载乐摇摇兑币机串口通信协议

下载主板协议对接操作指南

集成芯片****对接参考设计资料

若选择串口集成芯片对接方案，请下载相应参考资料

2G&WIFI-集成对接硬件设计资料

4G-集成对接硬件设计资料

SDK

下载[串口与函数SDK][SDK]

串口调试工具

下载乐摇摇串口调试助手

准备工作**：**对接前，需要先获取乐摇摇联网芯片或模组，以便后续开发测试。

如果您是首次接入乐摇摇联网方案，请按以下流程进行对接。下文将针对各个步骤进行详细描述。

通信接口： 串口（RS485/RS232/TTL）

波特率：38400

停止位：1位

数据位：8位

校验位：0位

协议采用小端模式(little-endian)的网络字节序来传递字和双字。

约定如下：

——字节(BYTE)的传输约定：按照字节流的方式传输；

——字(WORD)的传输约定：先传递低八位，再传递高八位；

——双字(DWORD)的传输约定：先传递低八位，然后传递高八位，再传递高16位，

最后传递高24位。

主机查询方式

主机按照一定的时间间隔向终端发送数据帧，终端接收到数据帧后返回应答帧，终端不主动上传数据，若主机在规定时间内未接受到规定的数据帧的应答数据帧，则重发数据帧直到终端返回应答数据帧。

正常通信时序：

异常通信时序：

终端上传数据帧方式

正常通信时序：

异常通信时序：

帧格式图

格式说明

兑币机 主板 -------------> 支付盒子

登录标识

登录标识是乐摇摇支付盒子用以识别所对接设备主板身份的标识码，每个产品都有且只有一个（请把登录标识烧录到设备中。当设备激活时，会上报到云端鉴权认证设备参数）。

标识码获取流程：

（1）打开乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器），输入账号密码并登录。若无账号，请先注册开发账号。

（2）登录成功后，即可进入开发者中心。

（3）点击创建产品出现弹窗，请按要求完善产品信息。

主板信息填写与要求 ：

1主板名称格式为厂家名称+设备类型，例如：乐摇摇****兑币机

2上传的主板原图与接线方式图片参照上方示例，特别注意拍摄清晰保证主板与支付盒子间的接口电路，以便工作人员审核

（4）主板信息提交成功后，乐摇摇硬件工作人员将在3个工作日内对其进行审核，审核结果会同步以短信形势发送到主板厂商预留的手机号码，请注意查收。

（5）待审核通过后，即可在该页面看到该主板对应登录标识。如未通过，请留意申请反馈并与乐摇摇硬件工作人员进一步沟通。

（6）注意：获取到的登录标识为十进制，通信数据中需转换为16进制，并令低位在前，高位在后，以小端模式传输。如：登录标识为150，则通信中实际需传输的登录标识数据为 0x96 0x00

支付流程

支付盒子

指令说明——云上分

支付盒子 -------------> 兑币机 主板

表1 支付盒子云上分指令数据区说明

兑币机 主板 -------------> 支付盒子

开发建议：投币数与金额默认取相同值，在实际应用中，建议兑币机上分数取投币数，兑币机取金额。

功能说明

1该指令用于配有显示屏的兑币机主板从支付盒子获取指向支付页面的二维码链接。

2该二维码链接的地址格式为：http://m.leyaoyao.com/lyy/t/

指令说明——获取二维码链接

兑币机 主板 -------------> 支付盒子

支付盒子 -------------> 兑币机 主板

功能说明

此功能不可去除，后台关于兑币机的收益、出礼等各项经营统计，皆基于本指令中数据完成。

其中，故障代码可根据厂商需求，在乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器打开）中的主板参数配置（参考设置终端参数）页面中最下方一栏自行定义。

创建故障参数：

点击添加，然后根据实际需求填写故障情况

编写完成提交后，点击同步主板参数，即可进行调试。

兑币机主板上报故障代码后，可以在乐摇摇手机后台的消息通知中接收到对应的故障信息，如下图所示

指令说明——终端主动上传账目增量

兑币机 主板 -------------> 支付盒子

表 2 终端主动上传账目增量指令数据区说明

支付盒子 -------------> 兑币机 主板

功能说明

此功能可以使兑币机主板主动获取到支付盒子当前的网络状态。需要注意，在开机约10分钟后，才可以正常获取到支付盒子的信号值。

指令说明——查询支付盒子网络状态

兑币机 主板 -------------> 支付盒子

支付盒子 -------------> 兑币机 主板

表 3 查询支付盒子网络状态指令数据区说明

功能说明

此功能可使主板厂家实现对其兑币机主板的远程升级，通过该指令，服务器将会把固件程序分包下发到主板。

首先进入开放平台开发者中心https://open.leyaoyao.com/factory/motherboard，点击固件远程升级，进入固件升级页面。

点击新增固件，填写各项信息，上传固件程序，点击确定。

在批量升级前，需要先进行验证固件操作，点击验证固件。根据盒子设备编号添加设备，验证固件最多选择两台，点击确定，即开始升级。

升级完成则后台显示升级成功。

此时可以进行批量升级操作，一次最多添加50台设备。

指令说明 —— 数据包下载

支付盒子 -------------> 兑币机主板

兑币机主板 -------------> 支付盒子

指令说明 —— 上传本地固件信息

兑币机主板------------->支付盒子

支付盒子 -------------> 兑币机主板

指令说明 —— 获取本地固件信息

支付盒子 -------------> 兑币机主板

兑币机主板------------->支付盒子

功能说明

厂商可通过此功能根据自身需求定义扩展指令，如清空当前局数，恢复出厂设置等功能。

在乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器打开）中的主板参数配置（参考终端参数）页面中，新增终端操作。

根据实际情况填写各项内容。若设置功能不含参，则该指令固定不含数据区；若设置功能含参，则需进一步设置子参数，具体可参考自定义终端参数项。设置中的功能码对应数据帧中的CMD项，数值范围0x30-0xC8（48-200）。

设置完成后，功能会显示在乐摇摇设备管理系统-设备管理模块中，右图4

指令说明——扩展指令

支付盒子 -------------> 兑币机 主板

兑币机 主板 -------------> 支付盒子

终端参数

指令说明——查询终端参数

支付盒子 -------------> 兑币机 主板

兑币机 主板 -------------> 支付盒子

指令说明——设置终端参数

支付盒子 -------------> 兑币机 主板

兑币机 主板 -------------> 支付盒子

自定义终端参数项

（1）打开乐摇摇后台网站https://open.leyaoyao.com（推荐Chrome浏览器），输入账号密码并登录开发者中心。若无账号，请先注册开发账号。

（2）在智能化产品列表中，找到需要进行自定义参数项的主板，点击“编辑”。若找不到该主板，请参照登录标识中的说明，添加需要对接的主板。

（3）进入主板参数配置页面，参数配置由3部分组成，包括基础参数、终端参数、故障参数。参数配置是对产品功能的抽象表示，可以通过不同功能类型定义。目前平台提供：布尔型、数值型、枚举型、故障型这四种参数类型。详情设置说明见参数配置

（4）界面预览

配置完成后，点击写一步，系统根据你配置的参数，自动生成设备参数管理界面，通过微信扫码二维码即可查看。确定功能、界面是否符合，若符合点击下一步即可，若不符合，返回参数配置界面调整。

（5）参数配置以及开发完成后，需要发布主板参数才完成入库对接。发布后，终端参数功能会显示在乐摇摇设备管理系统-设备管理模块中。

（6）当主板参数状态变为已发布后，即可进行对应的调试工作。若在此后修改参数项，需在修改完成后再次点击同步更新。

（7）发布后请厂商务必做好主板调试，主板调试完成，发布前请联系乐摇摇对接人员

本文档面向合作伙伴的技术员，适用于乐摇摇SAAS平台有屏售货机产品的硬件技术对接，便于双方技术团队遵循既定的合作流程，完成技术的沟通和对接，提升效率。

集成文档包括《技术协议文档》、《open-netty-client.jar》、《open-netty-client-sources.jar》

联系方式：陈先生-13728058558

设备接入SDK封装了有屏售货机与乐摇摇SAAS系统的云端通讯过程。 这些过程包括配置、连接、心跳、状态上报以及场景功能接口等。 使用SDK，可以使得开发者快速完成APP开发，开发者仅需关注APP的UI和UE设计即可，而相对复杂的协议与错误处理等事项可忽略。

第一步，和技术沟通，获得APP的产品参数appid和secrect。 第二部，下载SDK包和开发文档，实现场景应用接口。

下载安卓SDK

正式的域名:ehw.leyaoyao.com 端口:5923

合作方根据实际情况选择jar包的版本，可以在maven仓库查询maven和gradle依配置

仓库地址：https://mvnrepository.com

Gradle依赖

引入netty和json包

Mave依赖

开发团队已经对福袋机通讯协议进行封装，app只需要在工程中引入open-netty-client.jar，即可调用相应api进行数据收发操作。

登陆流程示意图

客户端实例声明

NettyClient client = new NettyClient ( appId , key , host , port , uuid,equipmentType, loginFlag,handler ) ;

client.connect(); // 请求服务器建立链接

参数说明:

消息处理器 消息子类继承AbstractMsgHandler，重写业务逻辑方法，详见“处理器实现”说明。 实现样例：

public class SimpleMsgHandler extends AbstractMsgHandler {

/**

重写登陆逻辑

**/

@Override

protected boolean loginHandler(ResponseParam responseParam) {

// 业务实现代码

return true;

}

……

方法名称：MsgProducer.getSignRandom(GetSignRandomParam param)。

该接口为 获取随机字串，获取随即字串接口是用于登录使用， SDK 在获取随即字段成功后会自动调用登录接口。如果自动登录接收登录结果为失败，需要手工调用该接口进行重试；

方法名称：MsgProducer.login(LoginParam param)。

如果登录结果返回失败，需要手动调用 getSignRandom(GetSignRandomParam param) 进行重新登录，建议重试时间间隔 5 秒。

SDK初始化成功后，自身机制管理与服务器链接状态，自动发起随机数获取、登陆，完成服务器约定的设备初始化流程。 步骤如下：

获取随机数 详见“获取随机字串”说明。

设备登陆 详见“设备登录接口”说明。

方法名：replyStartEq(ReplyStartEqParam param)

参数详细说明：

重写handler子类的sendAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override protected boolean startEquipmentHandler(ResponseParam responseParam) { super.startEquipmentHandler(responseParam); ReplyStartEqParam param = new ReplyStartEqParam(); param.setUniqueCode(responseParam.getK()); param.setData(0); // param.setData(1); // param.setFailure("主板启动失败"); return MsgProducer.replyStartEq(param); }

说明：设备收到此指令后应根据实际情况响应ser指令，否则服务端会隔5s重发该通知（k不变），最多重复3次

注意：如果设备应答的结果为失败，服务端会直接进行退款；应答成功则会根据启动结果上传esr指令进行判断是否启动成功。

方法名：uploadEqStartResult(ReplyStartEqParam param)

详细参数说明如下：

代码示例如下：

private static boolean uploadEqStartResult(String mi, String pi, String d, String k) { ReplyStartEqParam param = new ReplyStartEqParam(); param.setMi(Integer.parseInt(mi)); param.setPi(Integer.parseInt(pi)); int data = Integer.parseInt(d); if (data == 1) { param.setFailure("主板离线"); } param.setData(data); param.setUniqueCode(k); return MsgProducer.uploadEqStartResult(param); }

说明：设备将启动结果上报给服务端，如果启动结果失败时，服务端会进行退款，如果5s内未收到服务端下发的esrr指令，要进行重发（k不变），最多重发3次

注意：如果服务端在收到ser指令后，120s内没有接收到esr指令，则会认为设备启动成功

设备上报结果返回处理：

重写handler子类的eqStartResultReHandler方法，代码示例如下：

@Override protected boolean eqStartResultRespHandler(ResponseParam responseParam) { System.out.println(String.format("get 设备启动结果上传返回结果为：%s", gson.toJson(responseParam))); return true; }

当设备有线下投币的时候，需要调用 MsgProducer 中的 uploadCommonCoins方法 同步数据到服务端。 同步投币数据后 AbstractMsgHandler 中的 uploadCommonCoinsResultHandler方法会返回服务端的接收结果。 如果没有接收到消息或者返回接收失败，则需要进行 3次 重试；

方法名称：MsgProducer. uploadCommonCoins(UploadGiftParam param);   

详细参数说明如下：

代码示例如下：

public static boolean uploadCommonCoins(String total, String count) { System.out.println("上传投币信息......"); String key = UUID.randomUUID().toString(); CommonUploadCoinsParam param = new CommonUploadCoinsParam(); param.setUniqueCode(key); param.setTotal(total); param.setCount(count); return MsgProducer.uploadCommonCoins(param); }

代码示例：重写handler的uploadCommonCoinsResultHandler方法，处理消息通知。

@Override protected boolean uploadCommonCoinsResultHandler(ResponseParam responseParam) { System.out.println(String.format("get 上传投币信息返回结果为：%s", gson.toJson(responseParam))); return true; }

在公众号后台进行设备绑定和解除绑定操作，流程如下：

操作成功后，服务器下发的设备消息到安卓APP；如果操作失败，请开发这重复上述流程，重复操作流程不下发消息通知。

开发者实现handler的通知逻辑，重写eqBindNoticeHandler绑定通知；重写 eqUnBindNoticeHandler解绑通知。

示例代码如下：

/**

* 设备绑定通知

*@param responseParam

*@return

**/

protected boolean eqBindNoticeHandler(ResponseParam responseParam) {

System.out.println(String.format("get 收到设备绑定通知: %s", gson.toJson(responseParam)));

return true;

}

/**

*设备解绑通知

*@param responseParam

*@return

**/

@Override

protected boolean eqUnBindNoticeHandler(ResponseParam responseParam) {

System.out.println(String.format("get 收到设备解绑通知: %s", gson.toJson(responseParam)));

return true;

}

方法名：reportEquipmentFailure

参数详细说明：

示例代码：

public static boolean reportEquipmentFailure() { ReportEquipmentFailureParam param = new ReportEquipmentFailureParam(); param.setErrorCode("234"); param.setErrorDesc("设备故障上报测试"); param.setErrorStatus("1"); param.setUniqueCode(uuid()); return MsgProducer.reportEquipmentFailure(param); }

该操作需要确认上报结果，如果没有接收到消息或者返回接收失败，建议进行3次重试。

重写handler子类的reportEquipmentFailureResultHandler方法，接收故障上报结果。

代码示例：

@Override protected boolean reportEquipmentFailureResultHandler(ResponseParam responseParam) { System.out.println(String.format("上报设备错误信息 结果返回：%s", gson.toJson(responseParam))); return true; }

方法名： reportICCID

详细参数说明：

代码示例：

private static boolean iccidReport(String iccid) { System.out.println("上传iccid。。。。" + iccid); ICCIDParam param = new ICCIDParam(); param.setIccid(iccid); param.setUniqueCode(uuid()); return MsgProducer.reportICCID(param); }

说明：设备登录完成后，应上传iccid。如果5s内接收不到服务器响应，则需要重发该通知（uniqueCode不变），最多重发3次。

重写handler子类的reportICCIDResultHandler方法，接收服务器响应并处理。

代码示例：

@Override protected boolean reportICCIDResultHandler(ResponseParam responseParam) { System.out.println("Iccid 上报结果返回"); return super.reportICCIDResultHandler(responseParam); }

方法名：replyGps(ReplyGpsParam)

详细参数说明：

重写handler子类的gpsHandler方法，并响应服务器处理结果。

代码示例：

@Override protected boolean gpsHandler(ResponseParam responseParam) { super.gpsHandler(responseParam); ReplyGpsParam param = new ReplyGpsParam(); param.setUniqueCode(responseParam.getK()); param.setLongitude("113.38795"); param.setLatitude("22.9753936"); return MsgProducer.replyGps(param); }

方法名：replyQueryAds

详细参数说明：

重写handler子类的queryAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override protected boolean queryAdsHandler(ResponseParam responseParam) { super.queryAdsHandler(responseParam); ReplyQueryAdsParam param = new ReplyQueryAdsParam(); param.setUniqueCode(responseParam.getK()); param.setType("1"); param.setScreenWidth(100); param.setScreenHeight(100); param.setResolutionWidth(6700); param.setResolutionHeight(4000);

List positions = new ArrayList(); AdsPosition position1 = new AdsPosition(); position1.setValue("left0010"); position1.setName("左广告位"); position1.setArea("(0,0),(10,10)"); position1.setWidth(10); position1.setHeight(10); position1.setIsFullScreen("N"); position1.setScreenType("V");

AdsPosition position2 = new AdsPosition(); position2.setValue("right0010"); position2.setName("右广告位"); position2.setArea("(10,10),(60,60)"); position2.setWidth(40); position2.setHeight(40); position2.setIsFullScreen("N"); position2.setScreenType("H");

positions.add(position1); positions.add(position2); param.setPositions(positions); return MsgProducer.replyQueryAds(param); }

方法名：replySendAds

详细参数说明：

重写handler子类的sendAdsHandler方法，处理逻辑，并响应服务器处理结果。

代码示例：

@Override protected boolean sendAdsHandler(ResponseParam responseParam) { super.sendAdsHandler(responseParam); BaseParam param = new BaseParam(); param.setUniqueCode(responseParam.getK()); return MsgProducer.replySendAds(param); }

方法名：uploadAdsData(UploadAdsParam param)

参数详细说明：

为一个数组，各个参数名分别为：

说明：设备每分钟判断一次，如有播放广告，将播放数据上传到服务器统计。

重写handler子类的uploadAdsResultHandler方法，接收服务器的响应并处理。

代码示例：

@Override protected boolean uploadAdsResultHandler(ResponseParam responseParam) { return super.uploadAdsResultHandler(responseParam); }

方法名：replyUpdateAds

详细参数说明：

说明：服务器查询到广告信息有更新，会下发更新广告指令，设备若有此广告信息，根据状态值做相应的处理。

重写handler子类的updateAdsHandler方法，处理逻辑，并响应服务器处理结果。

@Override protected boolean updateAdsHandler(ResponseParam responseParam) { super.updateAdsHandler(responseParam); BaseParam param = new BaseParam(); param.setUniqueCode(responseParam.getK()); return MsgProducer.replyUpdateAds(param); }